<?php

namespace PhpYes\Com;

/**
 * Interface WebSessionInterface
 *
 * 实践总结，放入 session 中的东西(假设叫 存入物)的 生命 主要有 2 种:
 * 1. 存入物 的生命 同 session 的生命，可以 存活 到session结束 或者 被明确的 delete 掉
 * 2. 存入物 的生命 由具体的业务决定，可以 存活 业务设定的时间 或者 被明确的 delete 掉
 *
 * @package PhpYes\Com
 */
interface WebSessionInterface
{
    /**
     * 存入物 的生命 同 session 的生命
     * @param string $key
     * @param mixed $val
     */
    public function put($key, $val);

    /**
     * get 生命 同 session 的生命 的 存入物
     * @param string $key
     * @return mixed
     */
    public function get($key);

    /**
     * delete 生命 同 session 的生命 的 存入物
     * @param string $key
     */
    public function delete($key);

    /**
     * 存入物 的生命 由具体的业务决定
     * @param string $key
     * @param string $val - 注意: 类型是字符串类型
     * @param int $ttl - time to live, second
     */
    public function putex($key, $val, $ttl);

    /**
     * get 生命 由具体的业务决定 的 存入物
     * @param string $key
     * @return string
     */
    public function getex($key);

    /**
     * delete 生命 由具体的业务决定 的 存入物
     * @param string $key
     */
    public function deleteex($key);

    /**
     * session id 在所有 cookie 中的 key
     * @return string
     */
    public function getSessionKey();

    /**
     * session id 的前缀
     * @return string|null
     */
    public function getSessionIdPrefix();

    /**
     * session id
     * @return string|null
     */
    public function getSessionId();

    /**
     * session 存活的时间
     * @return int
     */
    public function getTtl();

    /**
     * session 剩下的存活时间
     * @return int
     */
    public function getTtlLeft();

    /**
     * session的cookie种到的域，默认是种到当前的域名下，不过有些情况下需要将session的cookie种到特定的域下，例如跨域开发时
     * @return string|null
     */
    public function getSessionDomain();

    /**
     * session
     * @return array|null
     */
    public function getSession();

    /**
     * session 创建时间戳
     * @return int
     */
    public function getCreateTs();

    /**
     * session ttl 更新时间戳
     * @return int
     */
    public function getUpdateTtlTs();

}